/**
 * @file bull_hal_net_https.h
 * @brief 
 * @author yejing (yejh@gongniu.cn)
 * @version 1.0
 * @date 2024-05-23
 * 
 * Copyright 2024-2025 GongNiu Inc. All Rights Reserved.
 * 
 */
#ifndef _BULL_HAL_NET_HTTPS_H_
#define _BULL_HAL_NET_HTTPS_H_

#include "bull_hal_adapter.h"



#ifdef __cplusplus
extern "C" {
#endif

#include "bull_hal_adapter.h"


/**
 * @brief 执行HTTPS客户端操作
 * 
 * 该函数用于通过HTTPS协议与服务器进行通信。它会发起一个HTTPS请求，并返回请求的结果。
 * 该函数用于执行HTTP客户端请求。它使用在esp_http_client_init函数中初始化并配置的选项来执行请求。
   该函数可以以阻塞或非阻塞方式执行请求，默认情况下以阻塞方式执行。
   若要启用非阻塞方式，需在调用esp_http_client_init函数时设置is_async成员。
   可以多次调用该函数，但必须在前一次调用返回后才能再次调用。
   注意，不能同时从两个地方使用相同的客户端句柄调用该函数。
   该函数包含esp_http_client_open、esp_http_client_write、esp_http_client_fetch_headers、
   esp_http_client_read（可选）和esp_http_client_close的功能。
   返回ESP_OK表示成功，返回ESP_FAIL表示错误。

 * @param https_client_handle 指向HTTPS客户端句柄的指针。该句柄用于标识唯一的HTTPS客户端实例。
 * @return OPERATE_RET 函数执行的状态码。成功时返回OPRT_OK，失败时返回其他错误码。
 */
OPERATE_RET bull_hal_net_https_client_perform( HTTPS_CLIENT_HANDLE *https_client_handle );


/**
 * @brief 该函数用于取消正在进行的HTTP请求。
 * 它通过关闭当前套接字并使用相同的esp_http_client上下文打开一个新的套接字来实现。
 * 该函数接受一个esp_http_client句柄作为参数，根据操作结果返回不同的错误码。
 * 
 * @param https_client_handle 
 * @return OPERATE_RET 
 */
OPERATE_RET bull_hal_net_http_client_cancel_request( HTTPS_CLIENT_HANDLE *https_client_handle );


/**
 * 设置HTTP客户端的URL
 * 
 * 本函数用于通过提供的URL来配置HTTP客户端的请求目标。它依赖于底层的HTTP客户端库来实现。
 * 
 * @param https_client_handle 指向HTTPS客户端句柄的指针。该句柄用于标识一个HTTP客户端实例。
 * @param url 指向以NULL结尾的URL字符串的指针。该URL指定客户端将要请求的资源位置。
 * 
 * @return 函数返回一个操作结果代码，成功时返回OPRT_OK，初始化未完成时返回OPRT_NOT_INIT，
 *         其他错误情况返回对应的错误码。
 */
OPERATE_RET bull_hal_net_http_client_set_url( HTTPS_CLIENT_HANDLE *https_client_handle, const char *url );


/**
 * 设置HTTP客户端的POST字段
 * 本函数用于配置HTTP客户端在发送POST请求时的字段内容。
 * 
 * @param https_client_handle 指向HTTPS客户端句柄的指针，用于标识特定的HTTP客户端实例。
 * @param data 要设置的POST字段的数据指针。
 * @param len POST字段数据的长度。
 * @return 函数执行状态码，成功返回OPRT_OK，失败返回相应的错误码。
 */
OPERATE_RET bull_hal_net_http_client_set_post_field( HTTPS_CLIENT_HANDLE *https_client_handle, const char *data, int len );


/**
 * @brief 设置HTTP客户端的请求头
 * 
 * 该函数用于在HTTP客户端的请求中添加、修改或删除指定的头字段。
 * 
 * @param https_client_handle 指向HTTPS客户端句柄的指针。
 * @param key 指定的头字段名称。
 * @param value 头字段的值。
 * @return OPERATE_RET 函数执行状态码，成功返回OPRT_OK，失败返回相应的错误码。
 */
OPERATE_RET bull_hal_net_http_client_set_header( HTTPS_CLIENT_HANDLE *https_client_handle, const char *key, const char *value );

OPERATE_RET bull_hal_net_http_client_set_username( HTTPS_CLIENT_HANDLE *https_client_handle, const char *username );

OPERATE_RET bull_hal_net_http_client_set_password( HTTPS_CLIENT_HANDLE *https_client_handle, const char *password );

OPERATE_RET bull_hal_net_http_client_set_user_data( HTTPS_CLIENT_HANDLE *https_client_handle, void **data );

OPERATE_RET bull_hal_net_http_client_get_user_data( HTTPS_CLIENT_HANDLE *https_client_handle, void **data );

OPERATE_RET bull_hal_net_http_client_set_method( HTTPS_CLIENT_HANDLE *https_client_handle, BULL_HTTP_CLIENT_METHOD_EUNM method );

OPERATE_RET bull_hal_net_http_client_set_timeout_ms( HTTPS_CLIENT_HANDLE *https_client_handle, int timeout_ms );

OPERATE_RET bull_hal_net_http_client_delete_header( HTTPS_CLIENT_HANDLE *https_client_handle, const char *key );

OPERATE_RET bull_hal_net_http_client_open( HTTPS_CLIENT_HANDLE *https_client_handle, int write_len );

OPERATE_RET bull_hal_net_http_client_write( HTTPS_CLIENT_HANDLE *https_client_handle, const char *buffer, int len );

OPERATE_RET bull_hal_net_http_client_fetch_headers( HTTPS_CLIENT_HANDLE *https_client_handle );

OPERATE_RET bull_hal_net_http_client_is_chunked_response( HTTPS_CLIENT_HANDLE *https_client_handle );

OPERATE_RET bull_hal_net_http_client_read( HTTPS_CLIENT_HANDLE *https_client_handle, char *buffer, int len );

OPERATE_RET bull_hal_net_http_client_get_content_length( HTTPS_CLIENT_HANDLE *https_client_handle );

/**
 * 从HTTP客户端获取状态码
 * 
 * 本函数用于通过HTTP客户端句柄获取服务器返回的状态码。
 * 
 * @param https_client_handle 指向HTTPS客户端句柄的指针。
 * @return 返回操作结果，如果成功则返回状态码，如果失败则返回错误码。
 */
OPERATE_RET bull_hal_net_http_client_get_status_code( HTTPS_CLIENT_HANDLE *https_client_handle );

OPERATE_RET bull_hal_net_http_client_close( HTTPS_CLIENT_HANDLE *https_client_handle );

OPERATE_RET bull_hal_net_http_client_cleanup( HTTPS_CLIENT_HANDLE *https_client_handle );


/**
 * @brief 注册HTTPS的服务
 * 
 * @param reg_params 
 * @return OPERATE_RET 
 */
OPERATE_RET bull_hal_net_https_register( BULL_HTTPS_REGISTER_T * reg_params, HTTPS_CLIENT_HANDLE *https_client_handle );



#ifdef __cplusplus
}
#endif


#endif